--- 文件系统模块：提供文件读写、目录操作、路径管理等文件系统相关功能


local fs = {}

-- 导入底层文件系统接口
local lib_fs = require("lib_fs")

---
-- 检查文件或目录是否存在
-- @param path 文件或目录路径
-- @return boolean 存在返回true，不存在返回false
---
function fs.exist(path)
    return lib_fs.exist(path)
end

---
-- 创建目录
-- @param path 目录路径
-- @return number 成功返回0，失败返回错误码
---
function fs.mkdir(path)
    return lib_fs.mkdir(path)
end

---
-- 删除目录（必须为空目录）
-- @param path 目录路径
-- @return number 成功返回0，失败返回错误码
---
function fs.rmdir(path)
    return lib_fs.rmdir(path)
end

---
-- 删除文件
-- @param path 文件路径
-- @return number 成功返回0，失败返回错误码
---
function fs.unlink(path)
    return lib_fs.unlink(path)
end

---
-- 重命名文件或目录
-- @param old_path 旧路径
-- @param new_path 新路径
-- @return number 成功返回0，失败返回错误码
---
function fs.rename(old_path, new_path)
    return lib_fs.rename(old_path, new_path)
end

---
-- 递归创建多级目录
-- @param path 多级目录路径
-- @return number 成功返回0，失败返回错误码
---
function fs.mkpath(path)
    return lib_fs.mkpath(path)
end

---
-- 拷贝文件或目录
-- @param src_path 源路径
-- @param dst_path 目标路径
-- @return number 成功返回0，失败返回错误码
---
function fs.copy(src_path, dst_path)
    return lib_fs.copy(src_path, dst_path)
end

---
-- 递归删除目录及其内容
-- @param path 目录路径
-- @return number 成功返回0，失败返回错误码
---
function fs.remove(path)
    return lib_fs.remove(path)
end

---
-- 获取文件状态信息
-- @param path 文件或目录路径
-- @return table 文件状态信息表
---
function fs.stat(path)
    return lib_fs.stat(path)
end

---
-- 打开文件
-- @param path 文件路径
-- @param mode 打开模式 ("r", "rw")
-- @return file_descriptor|nil 文件描述符，失败返回nil
---
function fs.open(path, mode)
    return lib_fs.open(path, mode)
end

---
-- 打开目录
-- @param path 目录路径
-- @return dir_descriptor|nil 目录描述符，失败返回nil
---
function fs.opendir(path)
    return lib_fs.opendir(path)
end

---
-- 简化的字符串文件读取函数
-- @param path 文件路径
-- @return string|nil 文件内容字符串，失败返回nil
---
function fs.readFile(path)
    local fd = fs.open(path, "r")
    if not fd then
        return nil
    end
    
    -- 获取文件大小
    local size = fd:size()
    if not size or size <= 0 then
        fd:close()
        return ""
    end
    
    -- 创建缓冲区读取文件内容
    local buf = require("lib_buf").create(size + 1)
    if not buf then
        fd:close()
        return nil
    end
    
    -- 读取文件内容
    local read_size = fd:read(buf, size)
    
    -- 清理资源
    fd:close()
    
    if read_size <= 0 then
        buf:destroy()
        return ""
    end
    
    -- 重置缓冲区位置并读取字符串
    buf:sleek(0)
    local content = buf:read_str()
    
    -- 销毁缓冲区
    buf:destroy()
    
    return content
end

---
-- 读取文件指定行内容
-- @param path 文件路径
-- @param lineNumber 行号，缺省为0（读取下一行）
-- @return string|nil 指定行的内容，失败返回nil
---
function fs.readLine(path, lineNumber)
    local fd = fs.open(path, "r")
    if not fd then
        return nil
    end
    
    -- 如果指定了行号，定位到文件开头
    if lineNumber and lineNumber > 0 then
        fd:seek(0, 0)
    end
    
    -- 读取指定行
    local line = fd:readline(lineNumber or 0)
    
    -- 关闭文件
    fd:close()
    
    return line
end

---
-- 简化的字符串文件写入函数
-- @param path 文件路径
-- @param content 要写入的字符串内容
-- @return boolean 是否写入成功
---
function fs.writeFile(path, content)
    local fd = fs.open(path, "rw")
    if not fd then
        return false
    end
    
    -- 写入内容
    local write_size = fd:write(content)
    
    -- 关闭文件
    fd:close()
    
    return write_size == #content
end

---
-- 使用缓冲区读取文件的函数
-- @param path 文件路径
-- @param buf 缓冲区对象
-- @param size 要读取的字节数，默认为全部内容
-- @return number|nil 实际读取的字节数，失败返回nil
---
function fs.readFileBuf(path, buf, size)
    local fd = fs.open(path, "r")
    if not fd then
        return nil
    end
    
    -- 如果未指定大小，读取全部内容
    if not size then
        size = fd:size() or 0
    end
    
    -- 读取文件内容到缓冲区
    local read_size = fd:read(buf, size)
    
    -- 关闭文件
    fd:close()
    
    return read_size
end

---
-- 使用缓冲区写入文件的函数
-- @param path 文件路径
-- @param buf 缓冲区对象
-- @param size 要写入的字节数
-- @return number|nil 实际写入的字节数，失败返回nil
---
function fs.writeFileBuf(path, buf, size)
    local fd = fs.open(path, "rw")
    if not fd then
        return nil
    end
    
    -- 保存当前缓冲区位置
    local current_pos = buf:sleek(0)
    
    -- 写入缓冲区内容到文件
    local write_size = fd:write(buf, size)
    
    -- 恢复缓冲区位置
    buf:sleek(current_pos)
    
    -- 关闭文件
    fd:close()
    
    return write_size
end

---
-- 读取目录内容
-- @param path 目录路径
-- @return table|nil 目录内容表，失败返回nil
---
function fs.readDir(path)
    -- 打开目录
    local dir_fd = fs.opendir(path)
    if not dir_fd then
        return nil
    end
    
    -- 创建结果表
    local entries = {}
    local entry_index = 1
    
    -- 读取目录中的所有条目
    while true do
        local entry = dir_fd:readdir()
        if not entry then
            break
        end
        
        -- 创建条目信息表
        local entry_info = {
            name = entry.name,       -- 文件名或目录名
            type = entry.type or "", -- 文件类型（"file" 或 "dir"）
            size = entry.size or 0,  -- 文件大小（目录为0）
            mtime = entry.mtime or 0 -- 修改时间
        }
        
        -- 添加到结果表
        entries[entry_index] = entry_info
        entry_index = entry_index + 1
    end
    
    -- 关闭目录
    dir_fd:close()
    
    return entries
end

return fs